Safewhere Identify 5.16

We are happy to announce the release of Safewhere Identify 5.16. In this topic, you will find the release notes for all new features and bug fixes in version 5.16, as well as any breaking changes when upgrading from previous versions.

New features and improvements

Safewhere Identify

Identify configurator

Skip backing up sources when upgrading Identify instance

The Identify configurator now includes a new setting called Skip backing up sources that allows you to bypass the source backup step. Instead, system administrators can use a PowerShell script to compress the source files of all instances or choose to back up the entire disk before carrying out an upgrade. Nevertheless, it is strongly recommended to have a backup before proceeding with the upgrade.

You can locate this setting on the Specific Settings step when upgrading an existing instance:

Alternatively, you can find it in the Mass upgrade wizard:

Furthermore, this feature is also supported in the CLI command line using the --skip-backup-source option.

Add report to show failed upgrade tenants during mass upgrade

We have enhanced the Identify configurator to log Identify instances encountering errors during mass upgrade process, including cases where Safewhere Admin fails to upgrade to the new version.

When an Identify instance experiences a failure during mass upgrade process, the Identify configurator now displays the following message after the last Identify instance completes its upgrade

Subsequently, you can locate the names of the failed instances in the error report CSV file for later correction:

This functionality is also available when using the CLI command line for upgrading multiple Identify instances:

OAuth 2.0 JWT Bearer grant type with input assertion signed by HMAC

We have improved the RFC7523 – OAuth 2.0 JWT Bearer grant type, now featuring support for JWT bearer where input assertion signed by HMAC.

To leverage the capabilities of OAuth 2.0 JWT grant type support, you can find more details on this topic.

Token revocation & introspection endpoints

As part of token management, Identify now provides the ability to access the token revocation (RFC 7009) and introspection (RFC 7662) endpoints.

Visit this link to effectively leverage these features for enhanced security and control over your tokens.

Clean up invalid and expired OAuth Access token data

If left uncontrolled, access token data can rapidly accumulate, leading to resource strain, security vulnerabilities, and operational inefficiencies.

In this version, Safewhere Identify introduces the ability to schedule the cleanup of invalid and expired access token data. You can find how to do this here.

And it is recommended that customers manually run scripts to delete all obsolete tokens before upgrading Identify instance to version 5.16.

More scripting extensible points in the scripting library

Starting from version 5.12, Safewhere Identify supported a scripting library and numerous extensible scripting points, allowing the integration of custom business logics into the Identify runtime pipeline through C# scripts.

In this version, Safewhere Identify introduces additional extensible scripting points, enabling users to:

• Customize an AuthnRequest sent to an upstream Identity Provider
• Conduct Home realm discovery
• Map the authentication context method class of the second factor to a desired value
• Define a policy specifying whether a token can be issued for a specific login
• Set a policy determining whether a user is allowed to register an MFA method
• Establish a policy determining whether an authentication request should be processed or rejected
• Select second factor methods that users can use

Similar to existing scripting points, you can create your scripts on the Scripting library page. To implement them, you only need to enter the script name in the scripting setting.

For more details on this topic, please refer to the Script library

Additionally, Safewhere Identify has updated the descriptions of some existing scripting points:

• Validate authentication context class that is sent via an AuthnRequest from this Service Provider is now Validate authentication context class that is sent via an AuthnRequest from a Service Provider.
• Validate authentication context class that is returned from this Identity Provider is now Validate authentication context class that is returned from an upstream Identity Provider.
• Map a requested authentication context class to a value that will be sent to this Identity Provider is now Map a requested authentication context class to a value that will be sent to an upstream Identity Provider.
• Select what Identity Providers that this Service Provider can use is now Select which Identity Providers a Service Provider can use (connection dependency customization).
• Customize second factor authentication is now Customize second factor authentication policy script.

Support using NameID to match logout request with authentication session

During the SLO process, Safewhere Identify extracts relevant information from a logout request to find out the requester and its participant entry in the participant list. From there, Identify also determines the SSO context and the participants that need to be logged out.

For SAML 2.0 logout requests, Safewhere Identify uses the SessionIndex from the logout request to identify the requester by default. Starting from this version, Identify provides the option Use NameID to match logout request with authentication session. If enabled, Identify only uses the NameID to find the logout candidate. If a logout candidate is identified through the matching of NameID, and the logout request contains a SessionIndex, the SessionIndex in the logout candidate must match the one in the logout request.

For OIDC logout request, the default matching is based on Client ID. Starting from this version, Safewhere Identify provides the option Use ‘sub’ claim to match logout request with authentication session. If enabled, Identify extracts the sub and uiId (SessionIndex) from the id_token_hint parameter. Then, Identify matches both of these pieces of information against the participant’s NameID and SessionIndex to find the logout candidate from the login participants.

To use NameID to match logout request with authentication session, you must use the NameID claim transformation to issue a NameID to the corresponding Service Provider connection.

For more information, please refer to this link.

Return bootstrap token (OAuth) from upstream IdP

Safewhere Identify now has the capability to return both an access token and a refresh token from an upstream OAuth Identity Provider to its Service Provider. You can find how to do this here.

MFA registration improvement

Previously, the T-OTP/WebAuthn registration flow behaved differently based on whether a user existed in the local database or not:

• For users existing in the local database, Identify stored their second factor registrations before successfully completing the Recovery Code step.
• For users not existing in the local database, Identify stored their second factor registrations after successfully completing the Recovery Code step.

To create consistency, we have decided to unify the two use cases and now persist data to the database after the successful conclusion of the Recovery Code step. In other words, the registration process concludes only when the user clicks the Continue button on the same page. Failure to click the Continue button will require users to repeat the registration process during their next login.

This change does not impact users who routinely complete the entire registration process. However, it is a breaking change for those accustomed to stopping before saving their recovery codes.

Notify to users about changes made to their authenticators

This feature enables the system to send notification emails to users when changes are made to their authenticators. Additionally, it fires an event to a service bus when configured, allowing external services to be notified of the changes as well. This helps to keep users informed and ensures seamless communication between the system and external services.

To enable this feature, navigate to the Security section in the Settings and set Notify users about changes made to their authenticators to Yes.

For more information, please refer to this link.

In this version, we only support notifications for password changes, T-OTP authenticators, WebAuthn authenticators, and device authentication.

New updates on Email templates

In this release, we have introduced two new email templates as described below:

• Notify users when authenticators change: This new email template is designed to notify users when there are changes made to their authenticators, such as adding, removing and changing authenticators from their account.
• Notify users when password change: This new email template is used to inform users when their password has been changed. It provides them with the necessary information and instructions to ensure the security of their account.

You can modify these email templates in Messaging > Templates.

You can find explanations for both email templates in the following link.

Password management

In this version, Safewhere Identify has made some improvements to password management:

1. Password leak database validation: This powerful policy takes proactive measures to ensure that your chosen passwords have not been compromised in previous data breaches. By comparing them against an extensive database of known compromised passwords from the excellent Have I Been Pawned service, it adds an additional layer of defense to protect users’ passwords. For more information, please refer to this link.
2. Password length restriction: Safewhere Identify enforces a password length restriction as recommended by https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#implement-proper-password-strength-controls to enhance security and maintain system efficiency. For now, we have set a maximum limit for password length at 1000 characters. This restriction is in place to strike a balance between security and practical usability. When a user enters a password with a length exceeding 1000 characters, Identify will return an error message: “The entered password, with a length of {password.Length}, exceeds the maximum allowed length. Please contact your system administrators to reset the password.”
3. Argon2id hashing algorithm support: Although Argon2id is one of the recommended, more modern algorithms by OWASP, Bcrypt remains the default algorithm for backward compatibility reasons. However, we understand that security preferences may vary, and therefore, we offer the flexibility to choose between these two algorithms. For more information, please refer to this link.

Ability to override browser’s default language

Safewhere Identify now allows you to change the language of your browser to suit your preferences. You can also customize the appearance and functionality of the language chooser page and add more languages using the hosted forms feature. This document will guide you through the steps to override browser’s default language.

Log Service Providers out individually instead of SLO

The SLO functionality is enabled by default. However, there are situations where a Service Provider may require individual logout for specific business needs. This document will guide you through the steps to configure individual logout.

Other improvements

• We have enhanced error validation for situations where the OS2faktor key cannot be unprotected.



• Upgrade the Metadata Service that Safewhere Identify uses for WebAuthn to the latest version (MDS3). As a result, the Fido Metadata service access key setting is no longer required and has been removed.
• Display the Connection Id below the Name field in the edit page of all connections and enable copying it to the clipboard.



• Enhance validation for verifying duplicate values when the identity-bearing claim’s value is not unique.
• Remove the redundant Audience value in assertions issued by Identify to its WSFederation applications.
• Display reset MFA methods option when hovering over the user on the user list, provided that the currently logged-in user has the UserContributor or Administrator role. Upon clicking, all MFA methods of the selected user will be reset.
• The Identify Admin and REST API can now correctly handle metadata that uses KeyInfo with KeyName.
• When opening an email template, the Default language code is now loaded automatically.



• Security Enhancement: Sensitive data, such as access_token, refresh_token, id_token, in the OAuth request and OAuth2.0 response, is now logged only partially to mitigate the risk of leaking complete tokens from log data.

IdentifyMe application

New supported hosted forms

Identify Admin allows you to customize both Identify and IdentifyMe views using hosted forms. Now, you can find distinct views for Identify and IdentifyMe.

To learn more about how to use hosted forms for your IdentifyMe views, check out this documentation.

Apply zxcvbn to evaluate user’s password strength

In this version, Identify Me uses zxcvbn, a password strength estimator inspired by password crackers, to evaluate the strength of user passwords. You can now get an accurate assessment of your password’s strength and take necessary measures to improve it.

Breaking changes

When upgrading your Identify instance from a previous version, you might encounter some changes:

Changes in Hosted forms

In summary, the breaking changes for Hosted forms encompass the following:

• Simplifying views to eliminate custom code used for preview purposes. The preview processing is centralized in one location — the SiteLayout. Please note that it overrides the window.load event, which can cause issues if your existing hosted forms also utilize the same event. This modification is specific to the updated default SiteLayout template. Therefore, if you’ve customized your SiteLayout, your customized version will still be applied, and this adjustment will not affect your hosted forms. If you’re using the Hosted forms feature for the first time and intend to use the window.load event in your hosted forms, feel free to remove the default window.load event from the SiteLayout. The default handler is only necessary for previewing and can be safely omitted.
• Forms have been modified to address bug fixes:
  • OS2faktorError
  • OnboardingSucceeded
  • OtpAuthenticationFailed
  • OtpAuthentication

Please refer this pull request for more details about the change.

Other changes

• Whenever the Identify OAuth server issues an access token, it will be stored in the database.
• All stored tokens (authorization code, refresh token, and access token) associated with the current login session are revoked immediately after the user logs out, regardless of whether the Allow token revocation and introspection setting is turned on or off.
• The Map a requested authentication context class to a value that will be sent to an upstream Identity Provider script type no longer has the input parameter cc (ControllerContext). If you save a script that uses cc, you will receive an error message: The name cc does not exist in the current context. To resolve this issue, simply remove the parameter cc from your script.

5.16 REST API change

You can find new changes on 5.16 APIs here.

Please note that there is also an important change regarding authorization. With the Access token revocation check functionality in place, we have added an option named Enable REST API Access token revocation check to perform revocation checks on access tokens used to access the REST API:

For backward compatibility, the option is off by default because enabling it for existing tenants would render all existing REST API’s access tokens and refresh tokens unusable. However, we strongly recommend that you enable it for your tenants where possible, especially for newly created ones.

5.16 known issues

You can find known issues of version 5.16 here.

Bug fixes

• Fixed: #96130 [IdentifyAdmin] Odd ReturnToLoginSelectorLink link and its corresponding message in OtpAuthenticationFailedView_Content text resource key within the OtpAuthenticationFailed razor view/hosted form
• Fixed: #105343 [IdentifyAdmin] Unable to update the SAML 2 Profile setting to OioSaml3 on the Settings page.
• Fixed: #103100 [IdentifyAdmin] Unable to set UnwireSmsGateway as default gateway from the list
• Fixed: #104019 [IdentifyAdmin] WSFederation application’s Entity ID comparison type setting in the connection tab keeps returning even when the search text does not contain its name in the search textbox
• Fixed: #102343 [IdentifyAdmin][OTP] Email/SMS claim type can be deleted despite being in use in OTP connection
• Fixed: #102678 [IdentifyAdmin] “Locked” status displays to all users in the searched user list when pressing the Search button after choosing All locked users in the advanced search user section
• Fixed: #102881 [IdentifyAdmin][Gateways] password is required error appears when configuring the existing Unwire SMS as the default gateway
• Fixed: #102946 [IdentifyAdmin] CSS load is not rendered occasionally on the sign-out page after a user chooses to log out from IdentifyAdmin
• Fixed: #103338 [IdentifyAdmin] Mass update wizard can include discrete claims whose `restrict elevation’ setting is active and the logged user has not registered any values in these claims
• Fixed: #102383 [OTP] Incorrect instructions regarding refreshing the page to request a new OTP code
• Fixed: #102405 [OTP] Click here to request a new OTP code. link disappears when entering an incorrect OTP code after reaching the OTP delivery interval.
• Fixed: #105074 [Runtime] Secrets are not correctly handled
• Fixed: #107150 [ErrorReport] Error Self-referencing loop detected with type ‘System.Security.Claims.Claim’. Path ‘IdpClaimsPrincipal.Claims[0].Subject.Claims’ occurs on the error report page when user tries to create an error report and already has a login session in his browser
• Fixed: #105708 [Logging] Debug items are missing from the logs when calling OAuth20 endpoints
• Fixed: #106502 [RESTAPI] Error code 404 is returned when triggering DELETE method on api/rest/v2/groups/many API with non-existing group
• Fixed: #106231 [RESTAPI] Error code 400 is returned with the message Unable to cast object of type ‘System.DateTime’ to type ‘System.String’ when calling User APIs with a DateTime value as the User claim value
• Fixed: #102346 [RESTAPI] The default mail gateway can be deleted using EmailConfiguration API
• Fixed: #104632 [RESTAPI] Error code 403 is returned with the message user is not found when triggering the PUT method to call the User APIs
• Fixed: #104636 [RESTAPI] Error code 500 is returned with the message Object reference not set to an instance of an object is returned when user content didn’t include the “urn:scim:schemas:extension:safewhere:identify:1.0” section
• Fixed: #105726 [IC/CLI] Network Service user is granted access permissions to the selfservice folder when creating a new Identify instance using Windows authentication
• Fixed: #106256 [IC/CLI] Network Service user is granted access permissions to the selfservice folder when upgrading an existing Identify instance using Windows authentication
• Fixed: #107117 [IC] Secrets are correctly handled when deploying an Identify instance
• Fixed: #106260 [IC] Data import throws an error message and stops when its in-use token is expired
• Fixed: #106963 [IC] Only instance XMLs belonging to the web server where the user triggers IC to configure the encryption key are encrypted
• Fixed: #106983 [IC] Error Cannot find the service ‘SqlQueryNotificationService-729bfc86-..-1ef8395fb40d’, because it does not exist or you do not have permission occurs occasionnly when deleting an Identify instance
• Fixed: #107048 [IC] Database connection error returns when accessing Safewhere Admin site after replicating an Identify instance using mongodb or cosmosdb as its audit provider
• Fixed: #102222 [IC] Unable to create a tenant using Windows authentication when the domain account’s password contains a ” character
• Fixed: #106871 [IC] “Token does not have enough informationToken does not have enough information” has logged when importing a group to a new Identify instance
• Fixed: #104309 [IdentifyMe] Status of Password contains all required characters requirement is not updated after clearing and setting new password
• Fixed: #106370 [IdentifyMe] The Access Denied page does not appear when a logged token from the upstream Identity Provider is unauthorized, for example, when it has multiple values for the urn:internal:userid claim
• Fixed: #102064 [IdentifyMe] T-OTP/WebAuthn authenticator pages lack validation to prevent XSS attack